Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / About Shape Objects

Shape Properties

The properties of a shape object for the most part define the basic geometric characteristics of the shape. Shape objects have nine accessible properties, as shown in Figure 2-2. Note that, because a shape is an object and not a data structure, the order of the properties as shown in Figure 2-2 is completely arbitrary. Properties in italics are references to other objects.

Figure 2-2 The shape object and its properties

The first six properties are specific to shape objects alone. They determine a shape's geometric type, geometric structure, fill, and references to other objects:

• Type. A value that specifies what type of geometry the shape object has. The different shape types include point, line, rectangle, text, glyphs, and so on. The section "Shape Type" beginning on page 2-9 describes the different shape types, and "Getting and Setting a Shape Object's Type, Fill, and Attributes" beginning on page 2-28 discusses how to manipulate this property.
• Geometry. A set of values that describes the specific graphic structure of the shape. For example, the geometry of a point shape specifies the two coordinates of the point. The geometry of a text shape specifies the sequence of characters or glyphs that it contains. Inside Macintosh: QuickDraw GX Graphics discusses the geometries of graphic shapes and Inside Macintosh: QuickDraw GX Typography discusses the geometries of typographic shapes. See also Figure 2-3 on page 2-12 of this chapter for a summary of shape geometries. The geometry property differs from other properties in one important respect: you can edit it directly. See "Directly Manipulating a Shape's Geometry" beginning on page 2-34 for more details.
• Fill. A value that determines how a shape is filled or framed when drawn. QuickDraw GX provides a number of different ways of filling a shape. For example, a rectangle shape might have a solid fill, which indicates that the shape represents a solid rectangle--that is, the entire area enclosed by the sides of the rectangle is included in the shape. Alternatively, a rectangle shape might have a framed fill, which indicates that the shape represents a hollow rectangle--only the lines connecting the rectangle's corners are included in this shape. The section "Shape Fill" beginning on page 2-13 discusses types of shape fills, and the section "Getting and Setting a Shape Object's Type, Fill, and Attributes" beginning on page 2-28 discusses how to manipulate the shape fill property of a shape object.
• Style, ink, and transform object references. References to the style object, ink object, and transform object that are needed to complete the specification of the shape. The section "Getting and Setting a Shape Object's Style, Ink, and Transform" beginning on page 2-30 discusses how to manipulate these references.

The remaining three shape properties are common to many QuickDraw GX objects (including styles, inks, and others):

• Attributes. A group of flags that control certain aspects of the behavior of the object. For a shape object, these flags allow you to specify where QuickDraw GX stores the shape object and how editing operations affect the shape object. For example, the gxMemoryShape attribute specifies that QuickDraw GX should avoid writing the shape object out to storage, and the gxMapTransformShape attribute indicates that certain editing operations, such as the GXMoveShape function, are to affect the data in the shape's transform object rather than the data in the shape itself. The section "Shape Attributes" beginning on page 2-16 describes the shape attribute flags, and the section "Getting and Setting a Shape Object's Type, Fill, and Attributes" beginning on page 2-28 discusses how to manipulate the attributes property of a shape object.
• Owner count. A number that indicates how many references to the object exist. The chapter "Introduction to QuickDraw GX" in this book includes general information about owner counts, and "Manipulating a Shape Object's Owner Count" beginning on page 2-31 describes when and how to examine and alter a shape object's owner count.
• Tag list. A list of references to custom information about the object, stored in private data structures called tag objects. The chapter "Tag Objects" in this book describes tag objects in general and how you can use them to add custom information to objects. The section "Getting and Setting a Shape Object's Tag References" beginning on page 2-32 discusses how to manipulate the tag objects associated with a shape object.

Shape Type

A shape object's type property specifies what sort of geometry the shape has. Table 2-1 lists the defined constants for each shape type and describes what each one means. (Note that the empty and full shape types are unusual, in that they have no specific geometry; they are used for specialized operations other than drawing.) The constants are defined in the gxShapeTypes enumeration.

Shape types (Continued)

Constant	Value	Explanation
gxEmptyType	1	An empty shape. It has no geometry, no contents, and no bounds. The intersection of two shapes that do not touch is the empty shape. You can use empty shapes as a starting point for collecting graphic elements. This shape type is described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxPointType	2	A point shape. Its geometry contains two fixed-point coordinate values representing the location of the point. This shape type is described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxLineType	3	A line shape. Its geometry contains two point geometries--the starting point and the ending point. This shape type is described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxCurveType	4	A curve shape. Its geometry contains three point geometries--a starting point, an ending point, and a control point--which together describe a quadratic Bézier curve. This shape type is described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxRectangleType	5	A rectangle shape. Its geometry contains four fixed-point values--representing the coordinates of the left, top, right, and bottom corners of the rectangle. This shape type is described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxPolygonType	6	A polygon shape. Its geometry includes any number of separate multiple-point polygon contours, each contour consisting of straight line segments connecting its points. This shape type is described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxPathType	7	A path shape. Its geometry includes any number of separate multiple-point path contours, each contour consisting of straight or curved line segments connecting its points. This shape type is described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxBitmapType	8	A bitmap shape. Its geometry contains information about the bitmap's size, shape, and color, as well as the pixel image itself. This shape type is described in the bitmap shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxTextType	9	A text shape. Its geometry contains a string of characters to be drawn with uniform stylistic properties such as font family, font size, and style. This shape type is described in the text shapes chapter of Inside Macintosh: QuickDraw GX Typography.
gxGlyphType	10	A glyph shape. Its geometry contains a string of glyphs, each of which may have its own typestyle when drawn. This shape type is described in the glyph shapes chapter of Inside Macintosh: QuickDraw GX Typography.
gxLayoutType	11	A layout shape. Its geometry contains a string of characters plus sophisticated formatting information that affects how the text is displayed. This shape type is described in the layout shapes chapter of Inside Macintosh: QuickDraw GX Typography.
gxFullType	12	A full shape. It encompasses all of the QuickDraw GX coordinate space. Inverting an empty shape produces a full shape. The full shape contains every other shape and no other shape contains the full shape. You can use full shapes to specify the largest possible clip area for maximum visibility when drawing. This shape type is described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxPictureType	13	A picture shape. It is a collection of other shapes, including possibly other picture shapes. This shape type is described in the picture shapes chapter of Inside Macintosh: QuickDraw GX Graphics.

Shape Geometry

Most shape geometries are defined in terms of points in a coordinate space. QuickDraw GX coordinates are pairs of fixed-point numbers (of type Fixed), as defined in the mathematics chapter of Inside Macintosh: QuickDraw GX Environment and Utilities. QuickDraw GX coordinate spaces are described in the chapter "View-Related Objects" in this book.

Figure 2-3 summarizes the contents of the geometry property for each type of QuickDraw GX shape (except empty and full types, which have no geometry). In the figure, elements of the geometry that are references (or arrays of references) to other objects are shown in italics. For a diagram showing all the properties of the basic QuickDraw GX objects, see the chapter "Introduction to Objects" in this book. For a diagram showing all the properties of the printing objects, see the introductory chapter of Inside Macintosh: QuickDraw GX Printing.

Figure 2-3 Shape geometry for each type of QuickDraw GX shape

The structures of individual shape geometries are specific to each shape type and thus are not described here. See the chapters of Inside Macintosh: QuickDraw GX Graphics and Inside Macintosh: QuickDraw GX Typography specified in Table 2-1 of the previous section for more information.

Nevertheless, some of the functions that affect shape geometry are common to all types of shapes, and are therefore described in this chapter. The section "Copying the Geometry From One Shape to Another" beginning on page 2-29 discusses how to copy the geometry between shapes. The section "Directly Manipulating a Shape's Geometry" beginning on page 2-34 discusses how to get direct access to a shape's geometry--as a data structure rather than as an object property--in order to modify it. Also, Figure 2-3 on page 2-12 of this chapter summarizes the contents of the geometry of each type of QuickDraw GX shape.

Shape Fill

Each shape object has a fill property. The shape fill specifies how QuickDraw GX interprets the geometry of the shape: how the shape is drawn, how the shape is hit-tested, and how certain geometric operations, like intersection or union, interpret the shape. Table 2-2 lists the defined constants for shape fill and describes what each one means. (Note that some shape fills have two or more equivalent names.) The constants are defined in the gxShapeFills enumeration.

Table 2-2 Shape fills (Continued)

Constant	Value	Explanation
gxNoFill	0	No fill--the shape is not filled at all. QuickDraw GX does not draw a shape with this shape fill and you may not perform geometric operations on it. You can use this shape fill to temporarily hide shapes or to prevent parts of a picture from drawing.
gxOpenFrameFill	1	Open-frame fill--the shape is outlined instead of filled. With this shape fill, QuickDraw GX interprets the shape as a connected series of straight or curved lines from the starting point of the shape geometry to the ending point (but not back to the starting point again).
gxFrameFill	1	Framed fill (same as gxOpenFrameFill).
gxClosedFrameFill	2	Closed-frame fill--the shape is outlined instead of filled. As with the open-frame fill, QuickDraw GX interprets the shape as a series of lines (or curves) from the starting point of the shape geometry to the ending point. However, in this case, QuickDraw GX also includes a line (or curve) from the ending point to the starting point, thus closing the contour.
gxHollowFill	2	Hollow fill (same as gxClosedFrameFill).
gxEvenOddFill	3	Even-odd fill--the shape is filled using the even-odd rule. See Figure 2-4 for an illustration of this rule; see Inside Macintosh: QuickDraw GX Graphics for further explanation.
gxSolidFill	3	Solid fill (same as gxEvenOddFill).
gxWindingFill	4	Winding fill--the shape is filled using the winding-number rule. See Figure 2-4 on page 2-14 for an illustration of this rule; see Inside Macintosh: QuickDraw GX Graphics for further explanation.
gxInverseEvenOddFill	5	Inverse even-odd fill--the shape is filled in an opposite manner from the even-odd rule; everything not filled using the even-odd rule is filled using this rule. See Inside Macintosh: QuickDraw GX Graphics for further explanation.
gxInverseSolidFill	5	Inverse solid fill (same as gxInverseEvenOddFill).
gxInverseFill	5	Inverse fill (same as gxInverseEvenOddFill).
gxInverseWindingFill	6	Inverse winding fill--the shape is filled using the winding-number rule and then inverted. See Inside Macintosh: QuickDraw GX Graphics for further explanation.

Figure 2-4 Even-odd and winding fills

Note that framed fill, hollow fill, and solid fill are alternative names for open-frame fill, closed-frame fill, and even-odd fill, respectively, and that both inverse solid fill and inverse fill are alternate names for inverse even-odd fill.

Not all shape fills make sense for all shape types. Table 2-3 shows the acceptable shape fills for each shape type (the alternative names are not listed). Note that empty and full shapes are permitted to have certain fill types even though they have no geometry.

Table 2-3 Valid shape fills for each shape type

Shape types	Valid shape fills
Empty	gxNoFill gxInverseEvenOddFill gxInverseWindingFill
Full	gxNoFill gxEvenOddFill gxWindingFill gxInverseEvenOddFill gxInverseWindingFill
Point, line, curve	gxNoFill gxOpenFrameFill
Rectangle	gxNoFill gxClosedFrameFill gxEvenOddFill gxWindingFill gxInverseEvenOddFill gxInverseWindingFill
Polygon, path	any shape fill
Text, glyph, layout	gxNoFill gxEvenOddFill gxWindingFill
Bitmap, picture	gxNoFill gxEvenOddFill

For additional examples of how different shape fills can affect the appearance of different types and geometries of shapes, see the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.

Shape Attributes

Each shape object includes a property that is a set of attributes, a group of flags that specify certain aspects of the shape's behavior. Table 2-4 lists the defined shape attribute constants and describes what each one means. The constants are defined in the gxShapeAttributes enumeration.

Shape attributes (Continued)

Constant	Value	Explanation
gxNoAttributes	0x0000	No shape attributes are set. You can use this attribute to clear or test against the current value of a shape's attributes.
gxDirectShape	0x0001	QuickDraw GX is to load the shape into directly accessible memory. Set this flag for shape objects that you don't want stored in accelerator card memory, or whose geometric structures you want to manipulate directly (see "Directly Manipulating a Shape's Geometry" beginning on page 2-34). The attributes gxDirectShape and gxRemoteShape are exclusive; do not set them both.
gxRemoteShape	0x0002	QuickDraw GX is to load the shape into remote memory (memory used by an accelerator card), if possible. When this flag is set, the shape might draw faster but you might not be able to edit the shape's geometry directly (see "Directly Manipulating a Shape's Geometry" beginning on page 2-34). The attributes gxRemoteShape and gxDirectShape are exclusive; do not set them both.
gxCachedShape	0x0004	QuickDraw GX is to prepare the shape for the fastest possible drawing by caching it compressed in an offscreen bitmap. (See "Caching Shape Objects" beginning on page 2-27; also, compare this with using the GXCacheShape function, described on page 2-62.)
gxLockedShape	0x0008	QuickDraw GX is to prohibit changes to the shape's geometry or the shape's disposal. You can use this flag in the debugging version of QuickDraw GX to prevent accidental modification of a shape intended to be used as a constant. When this flag is set, you cannot use the geometry-editing functions described in the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics and the text, glyph, and layout shapes chapters of Inside Macintosh: QuickDraw GX Typography. However, you can still alter the shape's geometric structure by accessing it directly (see "Directly Manipulating a Shape's Geometry" beginning on page 2-34).
gxGroupShape	0x0010	QuickDraw GX is to group all shapes within this shape as a single shape when hit-testing. This attribute applies to picture shapes only; for more information see the picture shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxMapTransformShape	0x0020	QuickDraw GX is to apply shape- transforming operations to the shape's transform object rather than to the shape's geometry. This attribute is set by default for bitmap shapes, picture shapes, and layout shapes. See the chapter "Transform Objects" in this book for more information on applying transformations to shapes.
gxUniqueItemsShape	0x0040	QuickDraw GX is to create a complete copy of each shape added to this picture rather than simply creating a reference to the added shape. This attribute applies to picture shapes only; for more information see the picture shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
gxIgnorePlatformShape	0x0080	QuickDraw GX is to treat the codes in the geometry of this shape as glyph codes rather than character codes. This attribute applies to typographic shapes only; for more information see the typographic shapes chapter of Inside Macintosh: QuickDraw GX Typography.
gxNoMetricsGridShape	0x0100	QuickDraw GX is not to use hints (special display instructions) provided with the font used for this shape. Set this attribute if you intend to manipulate text as a path shape; otherwise, the hinting can affect the spacing between the contours in the path's geometry and can be undesirable if you want to perform other operations such as scaling. This attribute applies to typographic shapes only; for more information see the typographic shapes chapter of Inside Macintosh: QuickDraw GX Typography.
gxDiskShape	0x0200	QuickDraw GX is to write this shape to disk before all shapes that do not have this attribute set when it needs to unload shapes to minimize memory requirements. The attributes gxDiskShape and gxMemoryShape are exclusive; do not set them both.
gxMemoryShape	0x0400	QuickDraw GX is to keep this shape loaded in memory as long as possible. When this attribute is set, QuickDraw GX writes this shape out to disk after all shapes are written that do not have this attribute set. The attributes gxMemoryShape and gxDiskShape are exclusive; do not set them both.